Based on a patch by Garrett Regier.
https://bugzilla.gnome.org/show_bug.cgi?id=617312
gtkcombobox.sgml
gtkcomboboxentry.sgml
gtkcontainer.sgml
+gtkdialog.sgml
gtkeditable.sgml
gtkentry.sgml
gtkentrybuffer.sgml
+gtkeventbox.sgml
gtkhbox.sgml
gtkiconview.sgml
gtkimcontextsimple.sgml
+++ /dev/null
-<!-- ##### SECTION Title ##### -->
-GtkDialog
-
-<!-- ##### SECTION Short_Description ##### -->
-Create popup windows
-
-<!-- ##### SECTION Long_Description ##### -->
-
-<para>
-Dialog boxes are a convenient way to prompt the user for a small amount of
-input, e.g. to display a message, ask a question, or anything else that does
-not require extensive effort on the user's part.
-</para>
-
-<para>
-GTK+ treats a dialog as a window split vertically. The top section is a
-#GtkVBox known as the <structfield>content_area</structfield>, and is
-where widgets such as a #GtkLabel or a #GtkEntry should be packed.
-The bottom area is known as the <structfield>action_area</structfield>.
-This is generally used for packing buttons into the dialog which may
-perform functions such as cancel, ok, or apply.
-</para>
-
-<para>
-GtkDialog boxes are created with a call to gtk_dialog_new() or
-gtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() is recommended;
-it allows you to set the dialog title, some convenient flags, and add simple
-buttons.
-</para>
-
-<para>
-If 'dialog' is a newly created dialog, the two primary areas of the window
-can be accessed through gtk_dialog_get_content_area() and
-gtk_dialog_get_action_area(), as can be seen from the example, below.
-</para>
-
-<para>
-A 'modal' dialog (that is, one which freezes the rest of the application from
-user input), can be created by calling gtk_window_set_modal() on the dialog. Use
-the GTK_WINDOW() macro to cast the widget returned from gtk_dialog_new() into a
-#GtkWindow. When using gtk_dialog_new_with_buttons() you can also pass the
-#GTK_DIALOG_MODAL flag to make a dialog modal.
-</para>
-
-<para>
-If you add buttons to #GtkDialog using gtk_dialog_new_with_buttons(),
-gtk_dialog_add_button(), gtk_dialog_add_buttons(), or
-gtk_dialog_add_action_widget(), clicking the button will emit a signal called
-"response" with a response ID that you specified. GTK+ will never assign a
-meaning to positive response IDs; these are entirely user-defined. But for
-convenience, you can use the response IDs in the #GtkResponseType enumeration
-(these all have values less than zero). If a dialog receives a delete event,
-the "response" signal will be emitted with a response ID of #GTK_RESPONSE_DELETE_EVENT.
-</para>
-
-
-<para>
-If you want to block waiting for a dialog to return before returning control
-flow to your code, you can call gtk_dialog_run(). This function enters a
-recursive main loop and waits for the user to respond to the dialog, returning the
-response ID corresponding to the button the user clicked.
-</para>
-
-<para>
-For the simple dialog in the following example, in reality you'd probably use
-#GtkMessageDialog to save yourself some effort. But you'd need to create the
-dialog contents manually if you had more than a simple message in the dialog.
-<example>
-<title>Simple <structname>GtkDialog</structname> usage.</title>
-<programlisting>
-
-/* Function to open a dialog box displaying the message provided. */
-
-void quick_message (gchar *message) {
-
- GtkWidget *dialog, *label, *content_area;
-
- /* Create the widgets */
-
- dialog = gtk_dialog_new_with_buttons ("Message",
- main_application_window,
- GTK_DIALOG_DESTROY_WITH_PARENT,
- GTK_STOCK_OK,
- GTK_RESPONSE_NONE,
- NULL);
- content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog));
- label = gtk_label_new (message);
-
- /* Ensure that the dialog box is destroyed when the user responds. */
-
- g_signal_connect_swapped (dialog,
- "response",
- G_CALLBACK (gtk_widget_destroy),
- dialog);
-
- /* Add the label, and show everything we've added to the dialog. */
-
- gtk_container_add (GTK_CONTAINER (content_area), label);
- gtk_widget_show_all (dialog);
-}
-
-</programlisting>
-</example>
-</para>
-
-<refsect2 id="GtkDialog-BUILDER-UI"><title>GtkDialog as GtkBuildable</title>
-<para>
-The GtkDialog implementation of the GtkBuildable interface exposes the
-@vbox and @action_area as internal children with the names "vbox" and
-"action_area".
-</para>
-<para>
-GtkDialog supports a custom <action-widgets> element, which
-can contain multiple <action-widget> elements. The "response"
-attribute specifies a numeric response, and the content of the element
-is the id of widget (which should be a child of the dialogs @action_area).
-</para>
-<example>
-<title>A <structname>GtkDialog</structname> UI definition fragment.</title>
-<programlisting><![CDATA[
-<object class="GtkDialog" id="dialog1">
- <child internal-child="vbox">"
- <object class="GtkVBox" id="vbox">
- <child internal-child="action_area">
- <object class="GtkHButtonBox" id="button_box">
- <child>
- <object class="GtkButton" id="button_cancel"/>
- </child>
- <child>
- <object class="GtkButton" id="button_ok"/>
- </child>
- </object>
- </child>
- </object>
- </child>
- <action-widgets>
- <action-widget response="3">button_ok</action-widget>
- <action-widget response="-5">button_cancel</action-widget>
- </action-widgets>
-</object>
-]]></programlisting>
-</example>
-</refsect2>
-
-<!-- ##### SECTION See_Also ##### -->
-
-<para>
-<variablelist>
-<varlistentry>
-<term>#GtkVBox</term>
-<listitem><para>Pack widgets vertically.</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>#GtkWindow</term>
-<listitem><para>Alter the properties of your dialog box.</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>#GtkButton</term>
-<listitem><para>Add them to the <structfield>action_area</structfield> to get a
-response from the user.</para></listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkDialog ##### -->
-<para>
-<structfield>vbox</structfield> is a #GtkVBox - the main part of the
-dialog box.
-</para>
-
-<para>
-<structfield>action_area</structfield> is a #GtkHButtonBox packed below the
-dividing #GtkHSeparator in the dialog. It is treated exactly the same
-as any other #GtkHButtonBox.
-</para>
-
-
-<!-- ##### SIGNAL GtkDialog::close ##### -->
-<para>
-
-</para>
-
-@dialog: the object which received the signal.
-
-<!-- ##### SIGNAL GtkDialog::response ##### -->
-<para>
-
-</para>
-
-@dialog:
-@arg1:
-
-<!-- ##### ARG GtkDialog:action-area-border ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkDialog:button-spacing ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkDialog:content-area-border ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkDialog:content-area-spacing ##### -->
-<para>
-
-</para>
-
-<!-- ##### ENUM GtkDialogFlags ##### -->
-<para>
-Flags used to influence dialog construction.
-</para>
-
-@GTK_DIALOG_MODAL: Make the constructed dialog modal,
- see gtk_window_set_modal().
-@GTK_DIALOG_DESTROY_WITH_PARENT: Destroy the dialog when its
- parent is destroyed, see gtk_window_set_destroy_with_parent().
-
-<!-- ##### ENUM GtkResponseType ##### -->
-<para>
-Predefined values for use as response ids in gtk_dialog_add_button().
-All predefined values are negative, GTK+ leaves positive values for
-application-defined response ids.
-</para>
-
-@GTK_RESPONSE_NONE: Returned if an action widget has no response id, or if
- the dialog gets programmatically hidden or destroyed.
-@GTK_RESPONSE_REJECT: Generic response id, not used by GTK+ dialogs.
-@GTK_RESPONSE_ACCEPT: Generic response id, not used by GTK+ dialogs.
-@GTK_RESPONSE_DELETE_EVENT: Returned if the dialog is deleted.
-@GTK_RESPONSE_OK: Returned by OK buttons in GTK+ dialogs.
-@GTK_RESPONSE_CANCEL: Returned by Cancel buttons in GTK+ dialogs.
-@GTK_RESPONSE_CLOSE: Returned by Close buttons in GTK+ dialogs.
-@GTK_RESPONSE_YES: Returned by Yes buttons in GTK+ dialogs.
-@GTK_RESPONSE_NO: Returned by No buttons in GTK+ dialogs.
-@GTK_RESPONSE_APPLY: Returned by Apply buttons in GTK+ dialogs.
-@GTK_RESPONSE_HELP: Returned by Help buttons in GTK+ dialogs.
-
-<!-- ##### FUNCTION gtk_dialog_new ##### -->
-<para>
-Creates a new dialog box. Widgets should not be packed into this #GtkWindow
-directly, but into the @vbox and @action_area, as described above.
-</para>
-
-@void:
-@Returns: a new #GtkDialog.
-
-
-<!-- ##### FUNCTION gtk_dialog_new_with_buttons ##### -->
-<para>
-
-</para>
-
-@title:
-@parent:
-@flags:
-@first_button_text:
-@Varargs:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_dialog_run ##### -->
-<para>
-
-</para>
-
-@dialog:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_dialog_response ##### -->
-<para>
-
-</para>
-
-@dialog:
-@response_id:
-
-
-<!-- ##### FUNCTION gtk_dialog_add_button ##### -->
-<para>
-
-</para>
-
-@dialog:
-@button_text:
-@response_id:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_dialog_add_buttons ##### -->
-<para>
-
-</para>
-
-@dialog:
-@first_button_text:
-@Varargs:
-
-
-<!-- ##### FUNCTION gtk_dialog_add_action_widget ##### -->
-<para>
-
-</para>
-
-@dialog:
-@child:
-@response_id:
-
-
-<!-- ##### FUNCTION gtk_dialog_set_default_response ##### -->
-<para>
-
-</para>
-
-@dialog:
-@response_id:
-
-
-<!-- ##### FUNCTION gtk_dialog_set_response_sensitive ##### -->
-<para>
-
-</para>
-
-@dialog:
-@response_id:
-@setting:
-
-
-<!-- ##### FUNCTION gtk_dialog_get_response_for_widget ##### -->
-<para>
-
-</para>
-
-@dialog:
-@widget:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_dialog_get_widget_for_response ##### -->
-<para>
-
-</para>
-
-@dialog:
-@response_id:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_dialog_get_action_area ##### -->
-<para>
-
-</para>
-
-@dialog:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_dialog_get_content_area ##### -->
-<para>
-
-</para>
-
-@dialog:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_alternative_dialog_button_order ##### -->
-<para>
-
-</para>
-
-@screen:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_dialog_set_alternative_button_order ##### -->
-<para>
-
-</para>
-
-@dialog:
-@first_response_id:
-@Varargs:
-
-
-<!-- ##### FUNCTION gtk_dialog_set_alternative_button_order_from_array ##### -->
-<para>
-
-</para>
-
-@dialog:
-@n_params:
-@new_order:
-
-
#include "gtkprivate.h"
#include "gtkbuildable.h"
+/**
+ * SECTION:gtkdialog
+ * @Short_description: Create popup windows
+ * @Title: GtkDialog
+ * @See_also: #GtkVBox, #GtkWindow, #GtkButton
+ *
+ * Dialog boxes are a convenient way to prompt the user for a small amount
+ * of input, e.g. to display a message, ask a question, or anything else
+ * that does not require extensive effort on the user's part.
+ *
+ * GTK+ treats a dialog as a window split vertically. The top section is a
+ * #GtkVBox, and is where widgets such as a #GtkLabel or a #GtkEntry should
+ * be packed. The bottom area is known as the
+ * <structfield>action_area</structfield>. This is generally used for
+ * packing buttons into the dialog which may perform functions such as
+ * cancel, ok, or apply. The two areas are separated by a #GtkHSeparator.
+ *
+ * #GtkDialog boxes are created with a call to gtk_dialog_new() or
+ * gtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() is
+ * recommended; it allows you to set the dialog title, some convenient flags,
+ * and add simple buttons.
+ *
+ * If 'dialog' is a newly created dialog, the two primary areas of the
+ * window can be accessed through gtk_dialog_get_content_area() and
+ * gtk_dialog_get_action_area(), as can be seen from the example below.
+ *
+ * A 'modal' dialog (that is, one which freezes the rest of the application
+ * from user input), can be created by calling gtk_window_set_modal() on the
+ * dialog. Use the GTK_WINDOW() macro to cast the widget returned from
+ * gtk_dialog_new() into a #GtkWindow. When using gtk_dialog_new_with_buttons()
+ * you can also pass the #GTK_DIALOG_MODAL flag to make a dialog modal.
+ *
+ * If you add buttons to #GtkDialog using gtk_dialog_new_with_buttons(),
+ * gtk_dialog_add_button(), gtk_dialog_add_buttons(), or
+ * gtk_dialog_add_action_widget(), clicking the button will emit a signal
+ * called #GtkDialog::response with a response ID that you specified. GTK+
+ * will never assign a meaning to positive response IDs; these are entirely
+ * user-defined. But for convenience, you can use the response IDs in the
+ * #GtkResponseType enumeration (these all have values less than zero). If
+ * a dialog receives a delete event, the #GtkDialog::response signal will
+ * be emitted with a response ID of #GTK_RESPONSE_DELETE_EVENT.
+ *
+ * If you want to block waiting for a dialog to return before returning
+ * control flow to your code, you can call gtk_dialog_run(). This function
+ * enters a recursive main loop and waits for the user to respond to the
+ * dialog, returning the response ID corresponding to the button the user
+ * clicked.
+ *
+ * For the simple dialog in the following example, in reality you'd probably
+ * use #GtkMessageDialog to save yourself some effort. But you'd need to
+ * create the dialog contents manually if you had more than a simple message
+ * in the dialog.
+ * <example>
+ * <title>Simple GtkDialog usage</title>
+ * <programlisting>
+ * /* Function to open a dialog box displaying the message provided. */
+ * void
+ * quick_message (gchar *message)
+ * {
+ * GtkWidget *dialog, *label, *content_area;
+ *
+ * /* Create the widgets */
+ * dialog = gtk_dialog_new_with_buttons ("Message",
+ * main_application_window,
+ * GTK_DIALOG_DESTROY_WITH_PARENT,
+ * GTK_STOCK_OK,
+ * GTK_RESPONSE_NONE,
+ * NULL);
+ * content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog));
+ * label = gtk_label_new (message);
+ *
+ * /* Ensure that the dialog box is destroyed when the user responds */
+ * g_signal_connect_swapped (dialog,
+ * "response",
+ * G_CALLBACK (gtk_widget_destroy),
+ * dialog);
+ *
+ * /* Add the label, and show everything we've added to the dialog */
+ *
+ * gtk_container_add (GTK_CONTAINER (content_area), label);
+ * gtk_widget_show_all (dialog);
+ * }
+ * </programlisting>
+ * </example>
+ *
+ * <refsect2 id="GtkDialog-BUILDER-UI"><title>GtkDialog as GtkBuildable</title>
+ * <para>
+ * The GtkDialog implementation of the #GtkBuildable interface exposes the
+ * @vbox and @action_area as internal children with the names "vbox" and
+ * "action_area".
+ * </para>
+ * <para>
+ * GtkDialog supports a custom <action-widgets> element, which
+ * can contain multiple <action-widget> elements. The "response"
+ * attribute specifies a numeric response, and the content of the element
+ * is the id of widget (which should be a child of the dialogs @action_area).
+ * </para>
+ * <example>
+ * <title>A <structname>GtkDialog</structname> UI definition fragment.</title>
+ * <programlisting><![CDATA[
+ * <object class="GtkDialog" id="dialog1">
+ * <child internal-child="vbox">"
+ * <object class="GtkVBox" id="vbox">
+ * <child internal-child="action_area">
+ * <object class="GtkHButtonBox" id="button_box">
+ * <child>
+ * <object class="GtkButton" id="button_cancel"/>
+ * </child>
+ * <child>
+ * <object class="GtkButton" id="button_ok"/>
+ * </child>
+ * </object>
+ * </child>
+ * </object>
+ * </child>
+ * <action-widgets>
+ * <action-widget response="3">button_ok</action-widget>
+ * <action-widget response="-5">button_cancel</action-widget>
+ * </action-widgets>
+ * </object>
+ * ]]></programlisting>
+ * </example>
+ * </refsect2>
+ */
struct _GtkDialogPrivate
{
gdk_event_free (event);
}
+/**
+ * gtk_dialog_new:
+ *
+ * Creates a new dialog box.
+ *
+ * Widgets should not be packed into this #GtkWindow
+ * directly, but into the @vbox and @action_area, as described above.
+ *
+ * Returns: the new dialog as a #GtkWidget
+ */
GtkWidget*
gtk_dialog_new (void)
{
G_BEGIN_DECLS
-/* Parameters for dialog construction */
+/**
+ * GtkDialogFlags:
+ * @GTK_DIALOG_MODAL: Make the constructed dialog modal,
+ * see gtk_window_set_modal()
+ * @GTK_DIALOG_DESTROY_WITH_PARENT: Destroy the dialog when its
+ * parent is destroyed, see gtk_window_set_destroy_with_parent()
+ *
+ * Flags used to influence dialog construction.
+ */
typedef enum
{
- GTK_DIALOG_MODAL = 1 << 0, /* call gtk_window_set_modal (win, TRUE) */
- GTK_DIALOG_DESTROY_WITH_PARENT = 1 << 1 /* call gtk_window_set_destroy_with_parent () */
+ GTK_DIALOG_MODAL = 1 << 0,
+ GTK_DIALOG_DESTROY_WITH_PARENT = 1 << 1
} GtkDialogFlags;
-/* Convenience enum to use for response_id's. Positive values are
- * totally user-interpreted. GTK will sometimes return
- * GTK_RESPONSE_NONE if no response_id is available.
+/**
+ * GtkResponseType:
+ * @GTK_RESPONSE_NONE: Returned if an action widget has no response id,
+ * or if the dialog gets programmatically hidden or destroyed
+ * @GTK_RESPONSE_REJECT: Generic response id, not used by GTK+ dialogs
+ * @GTK_RESPONSE_ACCEPT: Generic response id, not used by GTK+ dialogs
+ * @GTK_RESPONSE_DELETE_EVENT: Returned if the dialog is deleted
+ * @GTK_RESPONSE_OK: Returned by OK buttons in GTK+ dialogs
+ * @GTK_RESPONSE_CANCEL: Returned by Cancel buttons in GTK+ dialogs
+ * @GTK_RESPONSE_CLOSE: Returned by Close buttons in GTK+ dialogs
+ * @GTK_RESPONSE_YES: Returned by Yes buttons in GTK+ dialogs
+ * @GTK_RESPONSE_NO: Returned by No buttons in GTK+ dialogs
+ * @GTK_RESPONSE_APPLY: Returned by Apply buttons in GTK+ dialogs
+ * @GTK_RESPONSE_HELP: Returned by Help buttons in GTK+ dialogs
*
- * Typical usage is:
- * if (gtk_dialog_run(dialog) == GTK_RESPONSE_ACCEPT)
- * blah();
+ * Predefined values for use as response ids in gtk_dialog_add_button().
+ * All predefined values are negative, GTK+ leaves positive values for
+ * application-defined response ids.
*/
typedef enum
{
- /* GTK returns this if a response widget has no response_id,
- * or if the dialog gets programmatically hidden or destroyed.
- */
- GTK_RESPONSE_NONE = -1,
-
- /* GTK won't return these unless you pass them in
- * as the response for an action widget. They are
- * for your convenience.
- */
- GTK_RESPONSE_REJECT = -2,
- GTK_RESPONSE_ACCEPT = -3,
-
- /* If the dialog is deleted. */
+ GTK_RESPONSE_NONE = -1,
+ GTK_RESPONSE_REJECT = -2,
+ GTK_RESPONSE_ACCEPT = -3,
GTK_RESPONSE_DELETE_EVENT = -4,
-
- /* These are returned from GTK dialogs, and you can also use them
- * yourself if you like.
- */
- GTK_RESPONSE_OK = -5,
- GTK_RESPONSE_CANCEL = -6,
- GTK_RESPONSE_CLOSE = -7,
- GTK_RESPONSE_YES = -8,
- GTK_RESPONSE_NO = -9,
- GTK_RESPONSE_APPLY = -10,
- GTK_RESPONSE_HELP = -11
+ GTK_RESPONSE_OK = -5,
+ GTK_RESPONSE_CANCEL = -6,
+ GTK_RESPONSE_CLOSE = -7,
+ GTK_RESPONSE_YES = -8,
+ GTK_RESPONSE_NO = -9,
+ GTK_RESPONSE_APPLY = -10,
+ GTK_RESPONSE_HELP = -11
} GtkResponseType;
typedef struct _GtkDialogPrivate GtkDialogPrivate;
typedef struct _GtkDialogClass GtkDialogClass;
+/**
+ * GtkDialog:
+ *
+ * The GtkDialog struct contains only private fields
+ * and should not be directly accessed.
+ */
struct _GtkDialog
{
GtkWindow window;
GtkWidget* gtk_dialog_get_widget_for_response (GtkDialog *dialog,
gint response_id);
gint gtk_dialog_get_response_for_widget (GtkDialog *dialog,
- GtkWidget *widget);
+ GtkWidget *widget);
gboolean gtk_alternative_dialog_button_order (GdkScreen *screen);
void gtk_dialog_set_alternative_button_order (GtkDialog *dialog,
- gint first_response_id,
- ...);
+ gint first_response_id,
+ ...);
void gtk_dialog_set_alternative_button_order_from_array (GtkDialog *dialog,
gint n_params,
gint *new_order);
projects / gtk4.git / commitdiff